              <div align="right">
${TARGET="offline"}                <a href="${LDAP_SDK_HOME_URL}" style="font-size: 85%">LDAP SDK Home Page</a>
${TARGET="offline"}                <br>
                <a href="${BASE}index.${EXTENSION}" style="font-size: 85%">Product Information</a>
              </div>

              <h2>Using Additional UnboundID-Specific Controls</h2>

              <p>
                In addition to the controls documented on the
                <a href="../getting-started/controls.${EXTENSION}">Using Standard Controls</a>
                page of the Getting Started Guide, the UnboundID LDAP SDK for Java provides
                support for a number of other controls that are either less standardized or are
                specific to a particular server or set of servers.  These controls are only tested
                and assured to work with the Ping Identity, UnboundID, and Nokia/Alcatel-Lucent
                Directory Server and are not recommended for use in conjunction with any other
                type of server.
              </p>

              <p></p>
              <h3>Account Usable Controls</h3>

              <p>
                The account usable request control may be included in a search request to indicate
                that matching search result entries should include the corresponding response
                control.  The response control will indicate whether the user account associated
                with the search result entry is usable (i.e., whether attempts to authenticate as
                that user with valid credentials should succeed).  If the account is usable, then
                the control may also include the length of time until the user's password expires.
                If the account is not usable, then the response control may include information
                about why it is not usable including:
              </p>

              <ul>
                <li>
                  Whether the account has been inactivated
                </li>

                <li>
                  Whether the user must change his or her password before being allowed to do
                  anything else
                </li>

                <li>
                  Whether the user's password is expired
                </li>

                <li>
                  The number of remaining grace logins available to the user
                </li>

                <li>
                  The number of seconds until the account is automatically unlocked
                </li>
              </ul>

              <p>
                The following example performs a search to retrieve a user entry and determine
                whether it is usable.
              </p>

              <pre>
SearchRequest searchRequest =
     new SearchRequest("dc=example,dc=com", SearchScope.SUB, "(uid=john.doe)");
searchRequest.addControl(new AccountUsableRequestControl());
SearchResult searchResult = connection.search(searchRequest);

boolean isUsable = false;
for (SearchResultEntry entry : searchResult.getSearchEntries())
{
  for (Control c : entry.getControls())
  {
    if (c instanceof AccountUsableResponseControl)
    {
      AccountUsableResponseControl usableResponse =
           (AccountUsableResponseControl) c;
      isUsable = usableResponse.isUsable();
      if (isUsable)
      {
        System.out.println("The account is usable.");
      }
      else
      {
        System.err.println("The account is not usable.");
        List&lt;String&gt; unusableReasons =
             usableResponse.getUnusableReasons();
        if (! unusableReasons.isEmpty())
        {
          System.err.println("Unusable reasons:");
          for (String s : unusableReasons)
          {
            System.err.println("  " + s);
          }
        }
      }
    }
  }
}
</pre>

              <p></p>
              <h3>Administrative Operation Request Control</h3>

              <p>
                The administrative operation request control may be used to indicate that the
                associated operation is used for performing some administrative action in the
                server and is not associated with a "normal" client.  The server can use this
                information to treat the operation differently in some way (e.g., exclude it
                from the processing time histogram, or to include additional information about
                the operation in the server access log).
              </p>

              <p></p>
              <h3>Assured Replication Request and Response Controls</h3>

              <p>
                The assured replication request control can be used to request that the server
                delay the response to the associated operation until it has confirmed that it has
                met a minimum set of replication requirements.  This can be used for both
                durability (ensuring that the change is on at least one other server, or in at
                least one other data center) and for avoiding differences due to propagation delay
                (ensuring that the change will be visible on all servers in the local data center
                and/or across all data centers).  The corresponding response control provides
                information about whether the requested level of assurance was satisfied.
              </p>

              <p></p>
              <h3>Batched Transaction Specification Request Control</h3>

              <p>
                The batched transaction specification control is based on the definition in
                draft-zeilenga-ldap-txn and may be used to indicate that the associated add,
                delete, modify, or modify DN operation is part of a batched transaction.  The start
                batched transaction extended request should first be used in order to obtain the
                transaction ID, and then that transaction ID should be included in the batched
                transaction specification request control for all operations that are part of the
                transaction.  Once all operations which are to be part of the transaction have been
                requested, then the end batched transaction extended operation should be used to
                commit the operation.  See the
                <a href="extended-operations.${EXTENSION}">Extended Operations</A> page for more
                information about the start and end batched transaction operations and for an
                example illustrating their use.
              </p>

              <p></p>
              <h3>Exclude Branch Request Control</h3>

              <p>
                The exclude branch request control can be included in a search request to indicate
                that the search should not be processed in one or more branches of the DIT.
              </p>

              <p></p>
              <h3>Extended Schema Info Request Control</h3>

              <p>
                The extended schema info request control can be used to request that the server
                return extended information when retrieving the subschema subentry.  This extended
                information includes content like the name of the schema file in which the
                element is defined, and whether that schema element is considered read-only.
              </p>

              <p></p>
              <h3>Get Authorization Entry Request And Response Controls</h3>

              <p>
                The get authorization entry request control may be included in a bind request to
                ask the server to return the entries for the authentication and/or authorization
                identities resulting from the bind.  This is similar to the standard authorization
                identity request control, but retrieves the actual content of the authentication
                and authorization entries, and not just an authorization ID string.
              </p>

              <p></p>
              <h3>Get Backend Set ID Request And Response Controls</h3>

              <p>
                The get backend set ID request control may be included in a request expected to
                pass through an entry-balanced Directory Proxy Server to indicate which backend
                sets were used in the course of processing the operation.  This may be used in
                conjunction with the route to backend set request control to allow for more
                efficient routing of subsequent requests targeting the same entries.
              </p>

              <p></p>
              <h3>Get Effective Rights Request Control</h3>

              <p>
                The get effective rights request control may be included in a search request to
                determine what rights a given user has when interacting with entries matching the
                search criteria.
              </p>

              <p>
                The following example illustrates the process of including the get effective rights
                request control in a search request to determine whether user
                "uid=admin,dc=example,dc=com" has the ability to change the password for the user
                with uid "john.doe":
              </p>

              <pre>
SearchRequest searchRequest =
     new SearchRequest("dc=example,dc=com", SearchScope.SUB, "(uid=john.doe)",
                       "userPassword", "aclRights");
searchRequest.addControl(new GetEffectiveRightsRequestControl(
     "dn:uid=admin,dc=example,dc=com"));
SearchResult searchResult = connection.search(searchRequest);

for (SearchResultEntry entry : searchResult.getSearchEntries())
{
  EffectiveRightsEntry effectiveRightsEntry =
       new EffectiveRightsEntry(entry);
  if (effectiveRightsEntry.rightsInformationAvailable())
  {
    if (effectiveRightsEntry.hasAttributeRight(AttributeRight.WRITE,
                                               "userPassword"))
    {
      System.out.println("The admin user has permission to change the " +
                         "target user's password.");
    }
    else
    {
      System.out.println("The admin user does not have permission to " +
                         "change the target user's password.");
    }
  }
  else
  {
    System.err.println("No effective rights information was returned.");
  }
}
</pre>

              <p></p>
              <h3>Get Server ID Request And Response Controls</h3>

              <p>
                The get server ID request control may be included in a request expected to pass
                through a Directory Proxy Server to indicate which backend server(s) were used
                to process the operation.  This may be used in conjunction with the route to
                server request control to allow subsequent requests to be processed in the same
                backend server.
              </p>

              <p></p>
              <h3>Get User Resource Limits Request And Response Controls</h3>

              <p>
                The get user resource limits request control can be included in a bind request to
                request that the server return information about a number of resource limits and
                other properties for the authenticated user, including the search
                size/time/lookthrough limits, the idle time limit, the set of privileges assigned
                to the user, etc.
              </p>

              <p></p>
              <h3>Hard Delete Request Control</h3>

              <p>
                The hard delete request control may be included in a delete request to indicate
                that the server should permanently remove the entry, even if it would have
                normally performed a soft delete operation.
              </p>

              <p></p>
              <h3>Ignore NO-USER-MODIFICATION Control</h3>

              <p>
                The ignore NO-USER-MODIFICATION request control may be included in an add request
                to indicate that the entry to be added may include operational attributes which are
                defined with the NO-USER-MODIFICATION flag in the server schema.  Such attributes
                are generally not allowed to be altered by external clients, but in some cases it
                may be useful to do so (e.g., if you wish to move an entry from one server to
                another, or if you want to add an entry that had previously existed).
              </p>

              <p>
                The following example illustrates the process of including the get effective rights
                request control in a search request to determine whether user
                "uid=admin,dc=example,dc=com" has the ability to change the password for the user
                 with uid "john.doe":
              </p>

              <pre>
AddRequest addRequest = new AddRequest("dc=example,dc=com",
     new Attribute("objectClass", "top", "domain"),
     new Attribute("dc", "example"),
     new Attribute("creatorsName", "cn=Admin User DN"),
     new Attribute("createTimestamp", "20080101000000Z"));
addRequest.addControl(new IgnoreNoUserModificationRequestControl());

try
{
  LDAPResult result = connection.add(addRequest);
  System.out.println("The entry was added successfully.");
}
catch (LDAPException le)
{
  System.err.println("The attempt to add the entry failed.");
}
</pre>

              <p></p>
              <h3>Interactive Transaction Specification Request Control</h3>

              <p>
                The interactive transaction specification control may be used to indicate that the
                associated operation is part of an interactive transaction.  The start interactive
                transaction extended request should first be used in order to obtain the
                transaction ID, and then that transaction ID should be included in the interactive
                transaction specification request control for all operations that are part of the
                transaction.  Once all operations which are to be part of the transaction have been
                requested, then the end interactive transaction extended operation should be used
                to commit the operation.  See the <A HREF="extended-operations.${EXTENSION}">Extended
                Operations</A> page for more information about the start and end interactive
                transaction operations and for an example illustrating their use.
              </p>

              <p></p>
              <h3>Intermediate Client Controls</h3>

              <p>
                The intermediate client request control may be used to pass information about a
                client (and any clients which are downstream of it) on to a server, and the
                corresponding response control may be used to pass information about the server
                back to the client.  This can be very useful for tracking requests and responses
                through a directory environment (e.g., from a directory-enabled application,
                through a directory proxy server, to the directory server, and back).  Information
                that may be included in the request control includes:
              </p>

              <ul>
                <li>
                  Wrapped intermediate client request values from downstream clients.
                </li>

                <li>
                  The address of a downstream client system.
                </li>

                <li>
                  Whether communication with a downstream client is secure.
                </li>

                <li>
                  A requested authorization identity for the operation to be processed.
                </li>

                <li>
                  The name of the client application that is sending the request.
                </li>

                <li>
                  An identifier that may be used to identify the client session in the client
                  application.
                </li>

                <li>
                  An identifier that may be used to identify the corresponding request in the
                  client application.
                </li>
              </ul>

              <p>
                Information that may be included in the response control includes:
              </p>

              <ul>
                <li>
                  Wrapped intermediate client response values from upstream servers.
                </li>

                <li>
                  The address of an upstream server system.
                </li>

                <li>
                  Whether communication with an upstream server is secure.
                </li>

                <li>
                  The name of the server application that is sending the request.
                </li>

                <li>
                  An identifier that may be used to identify the client session in the server.
                </li>

                <li>
                  An identifier that may be used to identify the corresponding response in the
                  server.
                </li>
              </ul>

              <p>
                The following example illustrates the process of including an intermediate client
                request control in a search request to indicate that the request is coming from a
                client application named "my client" with a session identifier of "session123" and
                a request identifier of "request456":
              </p>

              <pre>
SearchRequest searchRequest =
     new SearchRequest("dc=example,dc=com", SearchScope.SUB, "(uid=john.doe)");
searchRequest.addControl(new IntermediateClientRequestControl(null, null,
     null, null, "my client", "session123", "request456"));
SearchResult searchResult = connection.search(searchRequest);

for (Control c : searchResult.getResponseControls())
{
  if (c instanceof IntermediateClientResponseControl)
  {
    IntermediateClientResponseControl intermediateClientResponse =
         (IntermediateClientResponseControl) c;
    System.out.println("Intermediate client response:  " +
         intermediateClientResponse.getResponseValue().toString());
  }
}
</pre>

              <p></p>
              <h3>Join Request and Result Controls</h3>

              <p>
                The LDAP join request control may be included in a search request to indicate that
                the server should also include information about entries that are related to the
                matching search result entries in some way.  The relation is specified using a
                join rule, and may include criteria like retrieving entries whose DNs are
                included in attribute values in the search result entry, retrieving entries that
                contain a specified attribute value from the search result entry,  or retrieving
                entries that contain an attribute value that matches the DN of the search result
                entry.
              </p>

              <p></p>
              <h3>Matching Entry Count Request and Response Controls</h3>

              <p>
                The matching entry count request control may be included in a search request to
                ask that the server return information about the number of entries that match the
                search criteria rather than actually returning the matching entries.  The request
                control has options that can make it possible to make trade-offs between speed
                and accuracy (e.g., whether to get an exact count, or whether it is acceptable to
                simply return an upper bound), and the corresponding response control includes
                information about how accurate the returned count is.
              </p>

              <p></p>
              <h3>No-Op Request Control</h3>

              <p>
                The LDAP no-op request control is defined in draft-zeilenga-ldap-noop, although
                because it has not yet been standardized no official OID has been allocated for
                this control and therefore it uses a temporary OID which is used by OpenLDAP,
                OpenDS, and the Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 Directory
                Server.  This control may be included in an add, delete, modify, or modify DN
                request to indicate that the server should perform as much processing as possible
                for the associated operation but should not actually make any changes to server
                data.  It may be used to verify whether the operation would likely be successful,
                and may include things like ensuring that the all of the necessary preconditions
                are met, that the requester has appropriate rights to perform the operation, and
                that the change would not violate the server schema.
              </p>

              <p>
                Note that operations including the LDAP no-op request control should never return a
                result of "SUCCESS", but if all processing up to the point at which the server
                would have applied the change to the data was successful, then it will return a
                "NO_OPERATION" result.  Otherwise, the server will return a response with the
                appropriate result code for the error that occurred.  The UnboundID LDAP SDK for
                Java will not throw an exception if the response includes the NO_OPERATION result
                code, but that result code will be included in the <tt>LDAPResult</tt> object that
                is returned.
              </p>

              <p>
                The following example demonstrates the use of the LDAP no-op request control to
                verify that a delete operation would likely succeed:
              </p>

              <pre>
ModifyRequest modifyRequest = new ModifyRequest("dc=example,dc=com",
     new Modification(ModificationType.REPLACE, "description", "new value"));
modifyRequest.addControl(new NoOpRequestControl());

try
{
  LDAPResult result = connection.modify(modifyRequest);
  if (result.getResultCode() == ResultCode.NO_OPERATION)
  {
    System.out.println("The modify would likely have succeeded.");
  }
  else
  {
    System.err.println("The modify would have failed.");
  }
}
catch (LDAPException le)
{
  System.err.println("The modify would have failed.");
}
</pre>

              <p></p>
              <h3>Operation Purpose Request Control</h3>

              <p>
                The operation purpose request control may be included in a request to provide
                additional information about the purpose of the associated operation, including
                elements like the name, version number, and code location for the application
                that issued the request, and a description of the purpose of that operation.  This
                is primarily used to provide additional access log information for that operation.
              </p>

              <p></p>
              <h3>Password Policy Controls</h3>

              <p>
                The password policy request and response controls are based on the definition in
                the draft-behera-ldap-password-policy Internet Draft.  The request control does not
                include any content, but the corresponding response control may include either,
                both, or neither of a warning element and an error element with information about
                the state of the associated user's account.  It is similar to (but somewhat more
                limited than) the account usable control.
              </p>

              <p>
                The following example will include the password policy request control in a bind
                request and retrieve the response control from the bind result:
              </p>

              <pre>
SimpleBindRequest bindRequest = new SimpleBindRequest(
     "uid=john.doe,ou=People,dc=example,dc=com", "password",
     new PasswordPolicyRequestControl());

Control[] responseControls;
try
{
  BindResult bindResult = connection.bind(bindRequest);

  // If we've gotten here, then the bind was successful but there may still
  // be a password policy warning included.
  responseControls = bindResult.getResponseControls();
}
catch (LDAPException le)
{
  // The bind failed.  There may be a password policy response control to
  // help tell us why.
  responseControls = le.getResponseControls();
}

for (Control c : responseControls)
{
  if (c instanceof PasswordPolicyResponseControl)
  {
    PasswordPolicyResponseControl pwpResponse =
         (PasswordPolicyResponseControl) c;

    PasswordPolicyErrorType errorType = pwpResponse.getErrorType();
    if (errorType != null)
    {
      System.err.println("Password policy error:  " + errorType.getName());
    }

    PasswordPolicyWarningType warningType =
         pwpResponse.getWarningType();
    if (warningType != null)
    {
      int value = pwpResponse.getWarningValue();
      switch (warningType)
      {
        case TIME_BEFORE_EXPIRATION:
          System.err.println("Your password will expire in " + value +
                             " seconds.");
          break;
        case GRACE_LOGINS_REMAINING:
          System.err.println("You have " + value +
                             " grace logins remaining.");
      }
    }
  }
}
</pre>

              <p></p>
              <h3>Password Validation Details Request and Response Controls</h3>

              <p>
                The password validation details request control may be included in an add, modify,
                or password modify request that attempts to set or update a user password.  The
                corresponding response control provides information about the result of password
                validation processing performed for that operation.  In the event that the
                provided password was rejected, this can provide more detailed information about
                which constraints were violated so that the application can present a more
                useful error response to the end user.
              </p>

              <p></p>
              <h3>Purge Password Request Control</h3>

              <p>
                The purge password request control may be included in a modify or password modify
                operation used to change a user password to indicate that the user's former
                password should be purged from the entry, even if the server configuration would
                normally have caused that password to be retired.  See the description of the
                retire password request control for a brief description of password retirement.
              </p>

              <p></p>
              <h3>Real Attributes Only Request Control</h3>

              <p>
                The real attributes only request control may be included in a search request to
                indicate that the server should only include the "real" attribute values in
                resulting entries and should not include the values of virtual attributes.  There
                is no corresponding response control.
              </p>

              <p>
                The following example illustrates the use of the real attributes only request
                control:
              </p>

              <pre>
SearchRequest searchRequest =
     new SearchRequest("dc=example,dc=com", SearchScope.SUB, "(uid=john.doe)");
searchRequest.addControl(new RealAttributesOnlyRequestControl());
SearchResult searchResult = connection.search(searchRequest);
</pre>

              <p></p>
              <h3>Replication Repair Request Control</h3>

              <p>
                The replication repair request control may be included in an update request to
                indicate that the associated change should be processed only on the server that
                receives the request and should not be replicated to any other server in the
                environment.  This may be used to take corrective action for any replication
                conflicts that have been detected but could not be automatically resolved.
              </p>

              <p></p>
              <h3>Retain Identity Request Control</h3>

              <p>
                The retain identity request control may be included in a bind request to indicate
                that the server should process the bind operation, but that it should not actually
                change the identity associated with the client connection.  This can be used to
                make it easier to process bind operations using connections that are part of a
                connection pool.  Rather than requiring a separate pool for bind operations or
                re-binding after each bind to restore the original identity, the retain identity
                control may be used to process the bind without destroying the authentication state
                of the pooled connection.
              </p>

              <p>
                The following example illustrates the use of the retain identity request control:
              </p>

              <pre>
SimpleBindRequest bindRequest = new SimpleBindRequest(
     "uid=john.doe,ou=People,dc=example,dc=com", "password",
     new RetainIdentityRequestControl());

try
{
  BindResult bindResult = connection.bind(bindRequest);
  // The bind was successful and the account is usable, but the identity
  // associated with the client connection hasn't changed.
}
catch (LDAPException le)
{
  // The bind was unsuccessful, potentially because the credentials were
  // invalid or the account is unusable for some reason (e.g., disabled,
  // locked, expired password, etc.).  The identity associated with the
  // client connection hasn't changed.
}
</pre>

              <p></p>
              <h3>Retire Password Request Control</h3>

              <p>
                The retire password request control may be included in a modify or password modify
                operation used to change a user password to indicate that the user's former
                password should temporarily be retained and remain usable in the entry for a
                period of time.  This can be useful in cases where it may be necessary to
                coordinate a password change across multiple applications or multiple instances of
                the same application.
              </p>

              <p></p>
              <h3>Return Conflict Entries Request Control</h3>

              <p>
                The return conflict entries request control may be included in a search request to
                indicate that the server should include any replication conflict entries (that
                are normally excluded from search results) that match the search criteria.
              </p>

              <p></p>
              <h3>Route to Backend Set Request Control</h3>

              <p>
                The route to backend set request control may be included in a request expected to
                pass through an entry-balanced Directory Proxy Server to provide information about
                which backend set(s) should be used in the course of processing the operation.
                This control may specify either an absolute routing request, to indicate that only
                the specified backend set(s) should be used, or a routing hint that may help
                provide better performance in cases where the Directory Proxy Server might
                otherwise have had to perform a broadcast across all backend sets to determine
                where to process the operation.
              </p>

              <p></p>
              <h3>Route to Server Request Control</h3>

              <p>
                The route to server request control may be included in a request expected to pass
                through a Directory Proxy Server to indicate which backend server should be used
                to process the operation.  This may be used to ensure that separate operations are
                processed by the same backend server to avoid the potential for problems that
                could arise as a result of replication propagation delay.
              </p>

              <p></p>
              <h3>Soft Delete Request and Response Controls</h3>

              <p>
                The soft delete request control may be included in a delete request to indicate
                that the target entry should not be immediately purged from the database but
                should instead be temporarily hidden.  A soft-deleted entry is normally not
                visible to clients, but it may be searchable using the soft-deleted entry
                access request control, and it may be restored using the undelete request control.
              </p>

              <p></p>
              <h3>Soft-Deleted Entry Access Request Control</h3>

              <p>
                The soft-deleted entry access request control may be included in a search request
                to indicate that the server should any return soft-deleted entries (which are
                normally excluded from search results) that match the search criteria.
              </p>

              <p></p>
              <h3>Suppress Operational Attribute Update Request Control</h3>

              <p>
                The suppress operational attribute update request control can be included in a
                request to indicate that the server should not alter one or more operational
                attributes that might otherwise be updated by the operation, including the last
                access time, last login time, last login IP address, creators name, create
                timestamp, modifiers name, and modify timestamp.
              </p>

              <p></p>
              <h3>Transaction Settings Request and Response Controls</h3>

              <p>
                The transaction settings request control may be included in a request in order
                to provide information used to tune the database transaction processing for
                the associated operation, including the commit durability, number of retry
                attempts, the transaction lock timeout, and whether to attempt to acquire an
                exclusive lock within the backend to ensure that no other operations may be
                in progress in the backend while the operation is being processed.
              </p>

              <p></p>
              <h3>Undelete Request Control</h3>

              <p>
                The undelete request control may be included in an add request to indicate that
                the add is an attempt to restore a soft-deleted entry to its original state
                (optionally with a different DN than had originally been used for the entry).
              </p>

              <p></p>
              <h3>Virtual Attributes Only Request Control</h3>

              <p>
                The virtual attributes only request control may be included in a search request to
                indicate that the server should only include virtual attribute values in resulting
                entries and should not include the values of "real" attributes.  There is no
                corresponding response control.
              </p>

              <p>
                The following example illustrates the use of the virtual attributes only request
                control:
              </p>

              <pre>
SearchRequest searchRequest =
     new SearchRequest("dc=example,dc=com", SearchScope.SUB, "(uid=john.doe)");
searchRequest.addControl(new VirtualAttributesOnlyRequestControl());
SearchResult searchResult = connection.search(searchRequest);
</pre>
